Enhance pragmatics documentation with new sections and examples#948
Enhance pragmatics documentation with new sections and examples#948Bananamilk452 wants to merge 4 commits into
Conversation
✅ Deploy Preview for fedify-json-schema canceled.
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the pragmatics documentation in docs/manual/pragmatics.md by adding new sections on addressing (to and cc), handling replies, allowing quotes (including FEP-044f and legacy Misskey quotes), and using Microformats 2 for embedding metadata in HTML. Since there are no review comments, I have no feedback to provide.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
📝 WalkthroughWalkthroughThe ActivityPub pragmatics manual now documents audience addressing, reply structure, quote consent policies, and Mastodon-compatible microformats with examples and interoperability guidance. ChangesActivityPub pragmatics documentation
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/manual/pragmatics.md`:
- Around line 801-804: Update the documentation paragraph to use consistent
`cc`/`ccs` terminology, and explicitly state that the enclosing `Create`
activity must copy the complete `to` and `cc` audience lists from its `Note`
object.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8317533f-a61b-4e1e-8fe6-8ec2e337993e
📒 Files selected for processing (1)
docs/manual/pragmatics.md
| The `to` and `cc` values are audience addresses, not inbox URLs. In particular, | ||
| use the parent author's actor URL in `cc`, then deliver the `Create` activity to | ||
| that actor through `Context.sendActivity()`. Give the enclosing `Create` | ||
| activity the same `to` and `cc` values as its `Note` object. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Keep the audience field names consistent.
The example sets ccs, but this paragraph refers only to matching cc values. Say cc/ccs and explicitly preserve the complete audience list when copying the Note audience onto the enclosing Create activity.
Suggested wording
-Give the enclosing `Create` activity the same `to` and `cc` values as its `Note` object.
+Give the enclosing `Create` activity the same `to`/`tos` and `cc`/`ccs` audience values as its `Note` object.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The `to` and `cc` values are audience addresses, not inbox URLs. In particular, | |
| use the parent author's actor URL in `cc`, then deliver the `Create` activity to | |
| that actor through `Context.sendActivity()`. Give the enclosing `Create` | |
| activity the same `to` and `cc` values as its `Note` object. | |
| The `to` and `cc` values are audience addresses, not inbox URLs. In particular, | |
| use the parent author's actor URL in `cc`, then deliver the `Create` activity to | |
| that actor through `Context.sendActivity()`. Give the enclosing `Create` | |
| activity the same `to`/`tos` and `cc`/`ccs` audience values as its `Note` object. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/manual/pragmatics.md` around lines 801 - 804, Update the documentation
paragraph to use consistent `cc`/`ccs` terminology, and explicitly state that
the enclosing `Create` activity must copy the complete `to` and `cc` audience
lists from its `Note` object.
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
dahlia
left a comment
dahlia
left a comment
There was a problem hiding this comment.
Please correct the three factual issues in the inline comments before this is merged. Please also link #946 from the pull request description so the accepted issue is visible from the pull request.
If an AI tool assisted with any part of this work, please name the tool and describe the extent of its assistance in the pull request description. Please read and follow AI_POLICY.md, and add an Assisted-by: AGENT_NAME:MODEL_VERSION trailer to every affected commit message.
| that actor through `Context.sendActivity()`. Give the enclosing `Create` | ||
| activity the same `to` and `cc` values as its `Note` object. | ||
|
|
||
| Mastodon and Pixelfed can require a remote reply to both `cc` the parent author |
There was a problem hiding this comment.
Mastodon uses inReplyTo, which Fedify serializes from replyTarget, to attach a reply to its parent thread. Putting the parent author in to or cc handles addressing and delivery, while a matching Mention tag lets Mastodon create a notification. Those fields do not establish the thread relationship. Please separate these roles instead of saying Mastodon requires both before adding the reply to the thread. If Pixelfed has a different requirement, please cite it separately.
| > and `QuoteAuthorization` terms also let implementations obtain, verify, and | ||
| > revoke the original author's consent. Fedify's `Note.quoteUrl` supports the | ||
| > legacy `_misskey_quote`, `quoteUrl`, and `quoteUri` properties for | ||
| > compatibility, while `Note.quote` and `Note.quoteId` represent FEP-044f's |
There was a problem hiding this comment.
The constructor accepts a quote value, but a Note instance does not expose a quote accessor. The generated API provides Note.quoteId and Note.getQuote() for the FEP-044f quote property. Please replace Note.quote with Note.getQuote() so the documentation names an API that readers can call.
| > [!TIP] | ||
| > Microformats are not required by ActivityPub, so a post remains valid without | ||
| > them. Nevertheless, adding them is recommended for interoperability with | ||
| > Mastodon, Misskey, and other implementations that recognize these conventions. |
There was a problem hiding this comment.
Please remove Misskey from this recommendation unless there is a source showing that its inbound federation code relies on these classes. Misskey's inbound HTML parser identifies mentions from the visible @ text and href, and identifies hashtags with ActivityPub tag data; it does not inspect h-card, u-url, mention, or hashtag classes. Misskey emits some of these classes, but that does not show that adding them improves inbound interoperability with Misskey. The recommendation is supported for Mastodon.
3 participants
This pull request adds comprehensive documentation to
pragmatics.mdon audience addressing, replies, quote policies, and microformats in ActivityPub objects. The new sections clarify how to use theto/ccproperties, create replies with proper audience and mentions, implement consent-respecting quote policies, and ensure interoperability with Mastodon and other platforms through microformats.Audience addressing:
toandccproperties (and their plural forms) for specifying primary and secondary recipients on ActivityPub objects, including code examples and links to further documentation.Replying and quoting:
Note.replyTarget, proper audience (to,ccs), andMentiontags, including a detailed code example. Explained requirements for Mastodon and Pixelfed compatibility.Microformats: